<!doctype html public "-//w3c//dtd html 4.0 transitional//en">


<!-- WARNING! This file is generated. -->
<!-- To alter documentation, edit files in src directory -->


<html><head>
<title>utOutput Package</title>
<link rel="stylesheet" href="utplsql.css" content="text/css">
<meta name="keywords" content="utPLSQL, PL\SQL, Unit Testing, Framework, Oracle"/>
<meta name="description" content="Unit Testing PL\SQL"/>
<meta name="title" content="utOutput Package"/>
<meta name="author" content="Steven Feuerstein, Chris Rimmer, Patrick Barel"/>
<meta name="copyright" content="(C) 2000-2005 Steven Feuerstein, Chris Rimmer, Patrick Barel"/>
</head><body>
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" border=0></a></div>
<p>[ <A href="index.html">Home</A>
 | <A href="started.html">Getting Started</A>
 | <A href="buildpack.html">Build Test Packages</A>
 | <A href="examples.html">Examples</A>
 | <A href="userguide.html">User Guide</A>
 | <A href="release.html">Release Notes</A>
 | <A href="map.html">Document Map</A> ]</p>
<p><A href="utgen.html">&lt; Previous Section: utGen Package</A> | <A href="utreceq.html">Next Section: utRecEq Package &gt;</A></p>
<!-- Begin utPLSQL Body -->
<!-- $Id: utoutput.html,v 1.3 2002/07/25 14:20:50 chrisrimmer Exp $ -->
<h1>
utOutput Package</h1>

<p>This package contains the following procedures and functions:
<br> 
<table cellspacing="5">
<tr>
<tr>
   <td width="25%"><a href="#Saving">utOutput.save</a></td>
   <td><a href="#Saving">Turn on the 'save' flag</a></td>
</tr>
   <td width="25%"><a href="#Saving">utOutput.nosave</a></td>
   <td><a href="#Saving">Turn off the 'save' flag</a></td>
</tr>
<tr>
   <td width="25%"><a href="#Saving">utOutput.saving</a></td>
   <td><a href="#Saving">Return the 'save' flag</a></td>
</tr>
<tr>
   <td width="25%"><a href="#Extract">utOutput.extract</a></td>
   <td><a href="#Extract">Pull text from the DBMS_OUTPUT buffer</a></td>
</tr>
<tr>
   <td width="25%"><a href="#Replace">utOutput.replace</a></td>
   <td><a href="#Replace">Replace saved output in the DBMS_OUTPUT buffer</a></td>
</tr>
<tr>
   <td width="25%"><a href="#NextLine">utOutput.nextLine</a></td>
   <td><a href="#NextLine">Pull the next line from the DBMS_OUTPUT buffer</a></td>
</tr>
<tr>
   <td width="25%"><a href="#Count">utOutput.count</a></td>
   <td><a href="#Count">Count the lines in the DBMS_OUTPUT buffer</a></td>
</tr>
</table>

<h2>Outline of Usage</h2>

<p>The problem with attempting to test output in PL/SQL is that there is a single
DBMS_OUTPUT buffer.  When your test is run, there may already be output in the
buffer from other tests, or from the tested code.  So what state should you
leave it in once you have finished?  Perhaps you want all the output created by
your tested code to end up in the buffer as if it had been run normally (i.e.
not from within utPLSQL), or maybe you want only the text that was in the
buffer before you started to be left.</p>

<p>This package attempts to allow to do any of these. There is a flag in the
package to determine whether text pulled from the output buffer should be
saved.  This is set with 'save' and 'nosave' and returned by
'saving'.  Data is pulled from the buffer using 'extract',
while the procedure 'replace' puts any saved data back into the output
buffer.</p>

<p>The intent is that it is used like this:</p>

<pre>
PROCEDURE ut_my_test IS
BEGIN

  --Pull out any text already in the output buffer
  utoutput.save;
  utoutput.extract;

  --Your testing code here, with saving turned on or off as you see fit

  --Put text back in the output buffer 
  utoutput.replace;

END;
</pre>

<p>So to start with, we save any text already in the buffer.  We then carry out
our testing.  If we want the output generated by the testing to end up back in
the output buffer, we turn on saving.  Finally, we put the saved text back.</p>

<h3>Warning</h3>
<p>In the current version of utPLSQL (2.0.9.1) use of this package is virtually impossible with 
<a href="utplsql.html#Trace">utPLSQL tracing</a> turned on.  The reason for this is that this facility writes output using 
DBMS_OUTPUT every time an assertion is called.</p>

<a name="Saving"><h2>Saving Output</h2></a>

<p>The three routines for handling the save flag are:</p>
<pre>
PROCEDURE save;

PROCEDURE nosave;

FUNCTION saving RETURN BOOLEAN;
</pre>

<p>Quite simply, 'save' turns the flag on, 'nosave' turns it off and 'saving'
returns its current value.</p>

<a name="Extract"><h2>Extracting Output</h2></a>

<p>There are 4 versions of the extract routine to get text from the output buffer:</p>

<pre>
FUNCTION extract (
   buffer_out    OUT DBMS_OUTPUT.CHARARR,
   max_lines_in  IN INTEGER := NULL,
   save_in       IN BOOLEAN := saving
) RETURN INTEGER;

PROCEDURE extract (
   buffer_out    OUT DBMS_OUTPUT.CHARARR,
   max_lines_in  IN INTEGER := NULL,
   save_in       IN BOOLEAN := saving
);

FUNCTION extract(
   max_lines_in  IN INTEGER := NULL,
   save_in       IN BOOLEAN := saving
) RETURN INTEGER;

PROCEDURE extract(
   max_lines_in  IN INTEGER := NULL,
   save_in       IN BOOLEAN := saving
);
</pre>

<p>The function versions return the number of lines extracted from the
DBMS_OUTPUT buffer. The other parameters are used as follows:
<ul>
   <li>buffer_out - This is a buffer in which to put the extracted text.</li>
   <li>max_lines_in - This is the maximum number of lines to be extracted.  If NULL is passed in (the default) then all the lines are extracted.</li>
   <li>save_in - This specifies if the extracted output should be saved.  It overrides the global save flag.</li>
</ul>
</p>

<a name="Replace"><h2>Replacing Output</h2></a>

<p>The replace procedure takes no parameters:</p>
<pre>
PROCEDURE replace;   
</pre>
<p>It simply puts the saved text back into the DBMS_OUTPUT buffer.  Note that the buffer is emptied at this point.</p>

<a name="NextLine"><h2>Checking Output Line-by-Line</h2></a>

<p>The nextLine function makes it easy to check output line-by-line as it
simply extracts and returns the next line of output:</p>

<pre>
FUNCTION nextLine(
  raise_exc_in BOOLEAN := TRUE, 
  save_in BOOLEAN := saving
) RETURN VARCHAR2;   
</pre>

<p>The raise_exc_in flag determines if the function should throw the exception utOutput.EMPTY_OUTPUT_BUFFER when asked for the next line from an empty buffer.  If no exception is thrown, NULL is returned.  As with extract, the save_in flag simply overrides the global save flag setting.
</p>

<a name="Count"><h2>Size of Output</h2></a>

<p>This function simply counts the number of lines present in the output buffer:</p>

<pre>
FUNCTION count RETURN INTEGER;   
</pre>

<p>Note that the output itself is left untouched.</p>

<!-- End utPLSQL Body -->
<p><A href="utgen.html">&lt; Previous Section: utGen Package</A> | <A href="utreceq.html">Next Section: utRecEq Package &gt;</A></p>
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" border=0></a></div>
<p class="copyright">Copyright (C) 2000-2005 <A href="mailto:steven@stevenfeuerstein.com">Steven Feuerstein<A>, <A href="mailto:c@24.org.uk">Chris Rimmer<A>, <A href="mailto:pbarel@vda.nl">Patrick Barel<A> All rights reserved</p>
</body></html>